Description

This PR proposes adding RetryableTransactionException for driver-specific transaction failures that are reasonable candidates for retrying the whole transaction, such as deadlocks and serialization failures.

The goal is to give CodeIgniter a small, conservative, driver-aware classification point without adding another public helper method to database connections. This follows the same direction as UniqueConstraintViolationException: when the driver recognizes a known database condition, it can throw a more specific exception type instead of a plain DatabaseException.

This can already help applications that want to implement their own retry policy:

try {
    $orderId = $db->transException(true)->transaction(static function ($db) use ($order) {
        $db->table('orders')->insert($order);

        return $db->insertID();
    });
} catch (RetryableTransactionException $e) {
    // Retry the whole transaction according to the application's policy.
    throw $e;
}

It is also intended as groundwork for a possible follow-up proposal to add opt-in retry support to the closure-based transaction() helper. Keeping the exception classification separate makes that later discussion smaller: retryable database errors can be reviewed independently from retry control flow, attempt counts, backoff behavior, and callback side-effect concerns.

This PR does not retry anything automatically. It only classifies known retryable transaction failures through a dedicated exception type.

Changes

• Added RetryableTransactionException, extending DatabaseException.
• Added centralized semantic exception creation in BaseConnection.
• Routed unique constraint and retryable transaction classification through the shared database exception factory.
• Added driver-specific retryable transaction classification.
• Simplified driver query execution paths to use the shared exception factory.
• Added focused tests for retryable, non-retryable, and unique-constraint exception classification.
• Updated the transaction docs and v4.8.0 changelog.

Driver Policy

The retryable classification is intentionally conservative. It includes transaction-level concurrency failures where retrying the whole transaction is a reasonable default:

• MySQLi deadlock: 1213
• Postgre serialization failure/deadlock: 40001, 40P01
• SQLite busy: 5
• SQLSRV deadlock/snapshot conflict: 1205, 3960
• OCI8 deadlock/serialization failure: 60, 8177

It intentionally does not classify lock timeouts, unique constraint violations, resource-busy errors, or SQLite extended busy codes as framework-default retryable transaction failures. Those can be valid retry cases in some applications, but they are more policy-dependent.

References: MySQL, PostgreSQL, SQLite, SQL Server deadlocks, SQL Server 3960, Oracle ORA-00060, Oracle ORA-08177.

Scope Note

This PR focuses on the normal driver query execution paths. Prepared queries still have separate exception paths today, similar to the existing unique-constraint behavior. I kept that out of this PR so it stays focused, but I’m happy to work on prepared-query exception consistency as a follow-up.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide